<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta http-equiv="Content-Language" content="en" />
    <title>skalibs: the djbtime library interface</title>
    <meta name="Description" content="skalibs: the djbtime library interface" />
    <meta name="Keywords" content="skalibs c unix djbtime library libstddjb" />
    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
  </head>
<body>

<p>
<a href="index.html">libstddjb</a><br />
<a href="../libskarnet.html">skalibs</a><br />
<a href="../index.html">skalibs</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>

<h1> The <tt>djbtime</tt> library interface </h1>

<p>
 The following functions are declared in the <tt>skalibs/djbtime.h</tt> header,
and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
</p>

<h2> General information </h2>

<p>
 <tt>djbtime</tt> is a set of functions to convert
<a href="tai.html">tai_t and tain_t</a> structures, and
<a href="http://cr.yp.to/libtai/tai64.html">TAI time</a>, from and to
other time formats and user-friendly representations.
</p>

<h2> Data structures </h2>

<ul>
 <li> TAI time with 1-second precision is represented as a <a href="tai.html">tai_t</a>. </li>
 <li> TAI time with more precision is represented as a <a href="tai.html">tain_t</a>. </li>
 <li> UTC time is represented as an unsigned 64-bit integer
equal to 2^62 added to the number of seconds since the Epoch. It's a trivial extension of
the standard 32-bit Unix time that will expire in 2038. </li>
 <li> Broken-down GMT or local time with more than a 1-second precision is stored in a
<tt>localtmn_t</tt> structure, containing a <tt>struct tm</tt> <em>tm</em>
field and an unsigned long <em>nano</em> field. </li>
</ul>

<h2> Functions </h2>

<h3> UTC </h3>

<p>
<code> int utc_from_tai (uint64_t *u, tai_t const *t) </code> <br />
Converts the absolute TAI64 time in *<em>t</em> to an UTC time, stored in
*<em>u</em> as an unsigned 64-bit integer. *<em>u</em> is actually 2^62
plus the number of seconds since the Epoch.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs.
</p>

<p>
<code> int tai_from_utc (tai_t *t, uint64_t u) </code> <br />
Converts the UTC time in <em>u</em>, stored
as an unsigned 64-bit integer (2^62 plus the number of seconds since
the Epoch), to a TAI64 time in *<em>t</em>.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs.
</p>

<h3> NTP </h3>

<p>
<code> int ntp_from_tain (uint64_t *ntp, tain_t const *a) </code> <br />
Converts the absolute TAI64N time in *<em>a</em> to a 64-bit NTP timestamp,
stored in *<em>ntp</em>. The higher 32 bits of *<em>ntp</em> represent a number
of seconds ; the lower 32 bits are the fractional part of the timestamp.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs (for instance:
*<em>a</em> cannot be represented in the valid NTP range).
</p>

<p>
<code> int tain_from_ntp (tain_t *a, uint64_t ntp) </code> <br />
Converts the NTP timestamp in <em>ntp</em> to a TAI64N time in
*<em>a</em>.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs.
</p>

<h3> Local time </h3>

<p>
 The following functions convert time between an internal representation
and a broken-down <tt>struct tm</tt>. Conversions are performed to
get leap seconds handling right, depending on whether skalibs has been
configured for a TAI-10 or a UTC system clock, and on whether the current
timezone takes leap seconds into account or not.
</p>

<p>
<code> int localtm_from_tai (struct tm *tm, tai_t const *t, int lo) </code> <br />
Converts the TAI time in *<em>t</em> to broken-down GMT (if
<em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in
*<em>tm</em>.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs (for instance: *<em>t</em> cannot be validly represented
in a struct tm).
</p>

<p>
<code> int localtm_from_utc (struct tm *tm, uint64_t u, int lo) </code> <br />
Converts the UTC time in <em>u</em> to broken-down GMT (if
<em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in
*<em>tm</em>.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs (for instance: <em>u</em> cannot be validly represented
in a struct tm).
</p>

<p>
<code> int localtm_from_sysclock (struct tm *tm, uint64_t u, int lo) </code> <br />
Converts the time in <em>u</em> to broken-down GMT (if
<em>lo</em> is zero) or local (if <em>lo</em> is nonzero) time in
*<em>tm</em>. <em>u</em> will be interpreted as a TAI-10 value (with
<tt>--enable-tai-clock</tt>) or as a UTC value (without <tt>--enable-tai-clock</tt>).
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs (for instance: <em>u</em> cannot be validly represented
in a struct tm).
</p>

<p>
<code> int utc_from_localtm (uint64_t *u, struct tm const *tm) </code> <br />
Converts the broken-down local time in *<em>tm</em> to an UTC value
in *<em>u</em>.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs.
</p>

<p>
<code> int tai_from_localtm (tai_t *t, struct tm const *tm) </code> <br />
Converts the broken-down local time in *<em>tm</em> to a TAI value
in *<em>t</em>.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs.
</p>

<p>
<code> int sysclock_from_localtm (uint64_t *u, struct tm const *tm) </code> <br />
Converts the broken-down local time in *<em>tm</em> to a value
in *<em>u</em> - either TAI-10 or UTC depending on your system clock.
The function returns 1 if it succeeds, or 0 (and sets errno) if an
error occurs.
</p>

<p>
 The following functions use the <tt>localtmn_t</tt> type to hold both
a broken-down time and a nanosecond count:
</p>

<pre>typedef struct localtmn_s localtmn_t, *localtmn_t_ref ;
struct localtmn_s
{
  struct tm tm ;
  uint32_t nano ;
} ;
</pre>

<p>
 The prototypes are self-explaining:
</p>

<p>
<code> int localtmn_from_tain (localtmn_t *tmn, tain_t const *a, int lo) ; <br />
int tain_from_localtmn (tain_t *a, localtmn_t const *tmn) ; <br />
int localtmn_from_sysclock (localtmn_t *tmn, tain_t const *a, int lo) ; <br />
int sysclock_from_localtmn (tain_t *a, localtmn_t const *tmn) ; </code> <br />
</p>

</body>
</html>
